<?xml version="1.0" encoding="UTF-8" ?>
<!--

    ﻿Copyright (C) 2009-2013 NewMain Softech

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
    either express or implied. See the License for the specific language
    governing permissions and limitations under the License.

-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 
	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
	<title>Maven GWT Template</title>
</head>
<body>
<h3>Maven GWT Template</h3>
<p>If you are having hard time with gwt-maven-plugin, then you may try this Maven GWT Template.<br /> 
</p>
<p><h4>Introduction</h4>
<ul>
	<li>The Maven GWT Template is for making GWT project adapt Maven project layout.</li>
	<li>Easy to customize to suit your needs/situation because it just consists of a pom.xml 
		template file and an Ant file.</li>
	<li>Intuitive and straight-forward to understand.</li>
</ul>
</p>
<p><h4>Recap about GWT</h4>
The development with GWT consists of the following steps:
<ol>
	<li>Writing code</li>
	<li>Pure JUnit test</li>
	<li>GWT dev-mode test (development mode test)</li>
	<li>Compilation by GWT compiler</li>
	<li>GWT prod-mode test (production mode test)</li>
	<li>Integration test</li>
	<li>Sign off</li>
</ol>
The GWT test class is the extension of GWTTestCase class. <br />
The GWT dev-mode test step and the GWT prod-mode test does not require explicit compilation by 
GWT compiler. <br />
So, the majority things can be done before explicit compilation by GWT compiler step, and you would 
repeat those steps more often than other at least ideally.<br />
Additionally to the above step, you may also have <br />
<ul>
	<li>GWT dev-mode (development mode) step for debugging<br />
		(Please be advised not to be confused the GWT dev-mode with the GWT dev-mode test: 
		the GWT dev-mode runs GWT code in the development mode so that you can check visually on 
		real browser rather than on HtmlUnit what GWT's JUnitShell uses, although GWT's JUnitShell 
		can be configured to use the real browser too.)
	</li>
	<li>i18n: Generating Constants/Messages interface</li>
	<li>Coding/generating asynchronous interface</li>
</ul>
</p>
<p><h4>How to use</h4>
<ol>
	<li>Create initial structure of your GWT project by using Maven't archetype.<br />
		<blockquote>
			<code>mvn archetype:generate <br />
				&nbsp;&nbsp;&nbsp;&nbsp;-DarchetypeRepository=repo1.maven.org <br />
				&nbsp;&nbsp;&nbsp;&nbsp;-DarchetypeGroupId=org.codehaus.mojo <br />
				&nbsp;&nbsp;&nbsp;&nbsp;-DarchetypeArtifactId=gwt-maven-plugin <br />
				&nbsp;&nbsp;&nbsp;&nbsp;-DarchetypeVersion=2.4.0 <br />
				&nbsp;&nbsp;&nbsp;&nbsp;-DgroupId=example -DartifactId=my-app
			</code>
		</blockquote>
	</li>
	<li>Download the Maven GWT Template files<br />
		<ul>
			<li><a href="https://code.google.com/p/gwetons/source/browse/trunk/gwt-maven-template/pom.xml">pom.xml</a><br />
				Switch the poject's pom.xml to the downloaded pom.xml with adding appropriate changes 
				to its content.<br />
				<b>Take a look at the properties section of the downloaded pom.xml file; the comments in 
				the properties section will give you more detail of the available customizable properties 
				for GWT settings.</b> Also check at the maven-antrun-plugin section as well to know what 
				Ant task will be executed for GWT compile/test at which life-cycle phase.<br />
			</li>
			<li><a href="https://code.google.com/p/gwetons/source/browse/trunk/gwt-maven-template/ant/antrun-gwt2.xml">antrun-gwt2.xml</a> 
			Ant build file<br />
			Create a folder named ant at the top of project folder, and place the downloaded 
			antrun-gwt2.xml file.
			</li>
		</ul>
		<br />
	</li>
	<li>Add your customization to the pom.xml template file.<br /> 
		<br />
	</li>
	<li><b>GWT test class name pattern</b><br />
		By default, it is assumed for the name of GWT test classes to follow this naming pattern: 
		<b>having the "<i>GwtTest</i>" prefix</b>. <u>This pattern is used to let maven-surefire-plugin 
		(what handles pure JUnit tests but GWT tests) to skip GWT test class &amp; suite</u>.<br />
		<br />  
	</li>
	<li><b>To run only pure JUnit tests</b><br />
		<blockquote>
			<code>mvn <b>-PJava_test_only test</b></code>
		</blockquote>
		JUnit tests will be executed by maven-surefire-plugin like regular Maven project.<br />
		You may provide true to gwt.devtest.skip property in your pom.xml instead:
		<blockquote>
			<code>
				&lt;project ...&gt;<br />
				&nbsp;&nbsp;&nbsp;&nbsp;...<br />
				&nbsp;&nbsp;&nbsp;&nbsp;&lt;<b>properties</b>&gt;<br />
				&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;...<br />
				&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
				&lt;<b>gwt.devtest.skip&gt;true&lt;/gwt.devtest.skip&gt;</b><br />
				&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;...<br />
				&nbsp;&nbsp;&nbsp;&nbsp;&lt;/properties&gt;
			</code>
		</blockquote>
	</li>
	<li><b>To run GWT dev-mode test</b><br />
		By default, the GWT dev-mode test will be <b>executed in the <i>test</i> life-cycle phase 
		(after pure JUnit test by maven-surefire-plugin)</b>. <br />
		Such as -DskipTests=true or -Dtest=NonGwtTestClass#nonGwtTestMethod, of course, the regular 
		parameters of maven-surefire-plugin work too to control pure JUnit test part being executed 
		before GWT dev-mode test(s).
		<ul>
			<li><b>To run All GWT test classes</b><br />
				<blockquote>
					<code>&gt;mvn <b>test</b></code>
				</blockquote>
				Though GWT's JUnitShell <b>automatically detects GWT tests extended from 
				GWTTestCase class</b>, <u>consider organizing your GWT tests into GWTTestSuite 
				class(es)</u> to get the best performance from your tests as GWT official 
				<a href="https://developers.google.com/web-toolkit/doc/latest/DevGuideTesting">Developer's Guide</a> 
				recommends. And <b>if you put your GWTTestCase class together into GWTTestSuite class(es), 
				then use either the gwt.devtest.testclass property (for single GWTTestSuite class) or 
				the gwt.devtest.incldue property to specify your GWTTestSuite class(es)</b>.<br />
				<br />
			</li>
			<li><b>To run GWT test class or GWT test suite</b>
				<ul>
					<li>Single GWT test class or single GWT test suite<br />
						Use gwt.devtest.testclass property.
						<blockquote>
							In pom.xml:<br />
							<code>
								&lt;project ...&gt;<br />
								&nbsp;&nbsp;&nbsp;&nbsp;...<br />
								&nbsp;&nbsp;&nbsp;&nbsp;&lt;<b>properties</b>&gt;<br />
								&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;...<br />
								&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
								&lt;<b>gwt.devtest.testclass</b>&gt;com.somepackage.GwtTestGoodLuck&lt;/gwt.devtest.testclass&gt;<br />
								&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;...<br />
								&nbsp;&nbsp;&nbsp;&nbsp;&lt;/properties&gt;<br />
							</code>
							and run<br />
							<code>&gt;mvn <b>test</b></code>
						</blockquote>
					</li>
					<li>Multiple GWT test classes or GWT test suites<br />
						With the gwt.devtest.incldue property, specify Ant style wild-cards 
						to include name of test classes to be run.
						<blockquote>
							In pom.xml:<br />
							<code>
								&lt;project ...&gt;<br />
								&nbsp;&nbsp;&nbsp;&nbsp;...<br />
								&nbsp;&nbsp;&nbsp;&nbsp;&lt;<b>properties</b>&gt;<br />
								&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;...<br />
								&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
								&lt;<b>gwt.devtest.incldue</b>&gt;com.somepackage.GwtTestToBeIncluded*&lt;/gwt.devtest.incldue&gt;<br />
								&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;...<br />
								&nbsp;&nbsp;&nbsp;&nbsp;&lt;/properties&gt;<br />
							</code>
							and run<br />
							<code>&gt;mvn <b>test</b></code>
						</blockquote>
					</li>
				</ul>
			</li>
			<li><b>To specify GWT test method</b> to be executed. <br />
				To specify test method in the single GWT test class, use gwt.devtest.testmethods property 
				addition to gwt.devtest.testclass property. To run multiple test methods, provides the  
				name of test methods delimited with ',' character to gwt.devtest.testmethods property.
				<blockquote>
					In pom.xml:<br />
					<code>
						&lt;project ...&gt;<br />
						&nbsp;&nbsp;&nbsp;&nbsp;...<br />
						&nbsp;&nbsp;&nbsp;&nbsp;&lt;<b>properties</b>&gt;<br />
						&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;...<br />
						&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
						&lt;<b>gwt.devtest.testclass</b>&gt;com.somepackage.GwtTestGoodLuck&lt;/gwt.devtest.testclass&gt;<br />
						&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
						&lt;<b>gwt.devtest.testmethods</b>&gt;test_red,test_green,test_blue&lt;/gwt.devtest.testmethods&gt;<br />
						&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;...<br />
						&nbsp;&nbsp;&nbsp;&nbsp;&lt;/properties&gt;<br />
					</code>
					and run<br />
					<code>&gt;mvn <b>test</b></code>
				</blockquote>
			</li>
		</ul>
		You may use either the GWT_dev_test profile (what is configure to skip the pure JUnit test) 
		or the Dev_test profile instead. <br />
		<br />
		The test report(s) will be saved to target/gwt-test-reports/htmlunit.dev folder by default.<br />
		If your test fails in mysterious way and you cannot figure out the cause, then try to add/change 
		<code>-logLevel=DEBUG</code> (or <code>-logLevel=TRACE</code>) to gwt.devtest.gwtargs property  
		in the pom.xml like:
		<blockquote>
			<code>
				&lt;<b>properties</b>&gt;<br />
				&nbsp;&nbsp;&nbsp;&nbsp;...<br />
				&nbsp;&nbsp;&nbsp;&nbsp;&lt;<b>gwt.devtest.gwtargs</b>&gt;<br />
				&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>-logLevel DEBUG</b><br />
				&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;-draftCompile  -standardsMode<br />
				&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;-war target/gwt-test-reports/htmlunit.dev<br />
				&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;-runStyle HtmlUnit:FF3<br />
				&nbsp;&nbsp;&nbsp;&nbsp;&lt;/gwt.devtest.gwtargs&gt;<br />
				&nbsp;&nbsp;&nbsp;&nbsp;...<br />
				&lt;/properties&gt;
			</code>
		</blockquote>
		Then check logged error in the text-format test report (with .txt extension) of your test.<br />
		If still puzzling event after that, running GWT dev-mode under debugger may shed light. Read on 
		to the next GWT dev-mode section.
		<br />
	</li>
	<li><b>To run GWT dev-mode</b> (for debugging or visual confirmation)<br />
		The GWT dev mode will be <b>skipped by default</b>. When it is enabled, it will be <b>executed in 
		the <i>process-classes</i> phase by default</b>. 
		<blockquote>
			<code>mvn <b>-PGWT_dev_mode process-classes</b></code>
		</blockquote>
		You may use the gwt.devmode.skip property instead. <br />
		<blockquote>
			In pom.xml:<br />
			<code>
				&lt;project ...&gt;<br />
				&nbsp;&nbsp;&nbsp;&nbsp;...<br />
				&nbsp;&nbsp;&nbsp;&nbsp;&lt;<b>properties</b>&gt;<br />
				&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;...<br />
				&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
				&lt;<b>gwt.devmode.skip</b>&gt;false&lt;/gwt.devmode.skip&gt;<br />
				&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;...<br />
				&nbsp;&nbsp;&nbsp;&nbsp;&lt;/properties&gt;<br />
			</code>
			and run<br />
			<code>&gt;mvn <b>process-classes</b></code>
		</blockquote>
		For debugging, you may also provide the gwt.devmode.jvmarg property in the properties section 
		of the pom.xml file like: 
		<blockquote>
			<code>
				&lt;<b>properties</b>&gt;<br />
				&nbsp;&nbsp;&nbsp;&nbsp;...<br />
				&nbsp;&nbsp;&nbsp;&nbsp;&lt;gwt.devmode.skip&gt;false&lt;/gwt.devmode.skip&gt;<br />
				&nbsp;&nbsp;&nbsp;&nbsp;&lt;<b>gwt.devmode.jvmarg</b>&gt;<br />
				&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>-Xdebug</b><br />
				&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>-Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5555</b><br />
				&nbsp;&nbsp;&nbsp;&nbsp;&lt;/gwt.devmode.jvmarg&gt;<br />
				&nbsp;&nbsp;&nbsp;&nbsp;...<br />
				&lt;/properties&gt;
			</code>
		</blockquote>
	</li>
	<li><b>To compile by GWT compiler</b><br />
		Compilation by GWTC will be <b>executed at the <i>prepare-package</i> phase by default</b>.<br />
		<blockquote>
			<code>mvn <b>prepare-package</b></code>
		</blockquote>
		By default, entering the above at command line also executes tests (pure JUnit tests, GWT dev-mode 
		test, and GWT prod-mode) because, as mentioned above, GWTC task is configured to be executed at 
		the prepare-package phase. If you like to skip those tests and just compile, then you may 
		add a profile for this to your pom.xml with providing <code>skipTests</code>, 
		<code>gwt.devtest.skip</code> and <code>gwt.prodtest.skip</code> properties like:
		<blockquote>
			<code>
				&lt;profiles&gt;<br />
				&nbsp;&nbsp;&nbsp;&nbsp;...<br />
				&nbsp;&nbsp;&nbsp;&nbsp;&lt;<b>profile</b>&gt;<br />
				&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;id&gt;for_GWTC&lt;/id&gt;<br />
				&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;<b>properties</b>&gt;<br />
				&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
				&lt;<b>skipTests</b>&gt;true&lt;/skipTests&gt;<br />
				&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
				&lt;<b>gwt.devtest.skip</b>&gt;true&lt;/gwt.devtest.skip&gt;<br />
				&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
				&lt;<b>gwt.prodtest.skip</b>&gt;true&lt;/gwt.prodtest.skip&gt;<br />
				&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;/properties&gt;<br />
				&nbsp;&nbsp;&nbsp;&nbsp;&lt;/profile&gt;<br />
				&nbsp;&nbsp;&nbsp;&nbsp;...<br />
			</code>
		</blockquote>
	</li>
	<li><b>To run GWT prod-mode test</b><br />
  		The GWT production-mode test will be <b>executed in the <i>prepare-package</i> phase by default</b>. 
		<blockquote>
			<code>mvn <b>prepare-package</b></code>
		</blockquote>
		The properties for the GWT prod-mode test are almost identical to ones for for the GWT 
		dev-mode test except the followings:
		<ul>
			<li>In each name of properties, "prodtest" token is used instead of "devtest" token.</li>
			<li>The default value for the gwt.prodtest.gwtargs property has a little difference from 
			one for the gwt.devtest.gwtargs property.
			</li>
			<li>The default destination folder of the test reports will be 
			target/gwt-test-reports/htmlunit.prod folder instead of 
			target/gwt-test-reports/htmlunit.dev folder. 
			</li>
		</ul> 
	</li>
</ol>
</p>
<p><h4>Example</h4>
For an usage example, you may also refer to the actual 
<a href="https://code.google.com/p/gwetons/source/browse/trunk/pom.xml">pom.xml file of this project</a>.
</p>
<p><u><h4>Notes/Reminders</h4></u>
<ul>
	<li>properties section in pom.xml
		<ul>
			<li>gwt.version : Specify the same version in Eclipse preferences.
			</li>
		</ul>
	</li>
	<li>Again, the behaviors will be easily customizable because it's just done by 
	the <a href="https://code.google.com/p/gwetons/source/browse/trunk/gwt-maven-template/pom.xml">pom.xml</a> 
	file and the <a href="https://code.google.com/p/gwetons/source/browse/trunk/gwt-maven-template/ant/antrun-gwt2.xml">antrun-gwt2.xml</a> 
	Ant build file.
	</li>
</ul>
</p>
</body>
</html>